rust-releases
Introduction
The Rust programming language uses deterministic versioning for toolchain releases. Stable versions use SemVer, while nightly, beta and historical builds can be accessed by using dated builds (YY-MM-DD).
Unfortunately, a clean index of releases is not available any more. I decided to research which resources where still available and found the following solutions:
- Use the AWS index (source)
- Build from individual release manifests (source)
- Parse Rust in-repo RELEASES.md
Each of these options requires additional parsing, which is where this crate comes in: the rust-releases crate
can obtain, parse and build an index from the above resources. This crate also provides methods to iterate over versions
in a linear fashion, or by using a bisect binary search strategy.
Each data source implements the Source trait. Source provides a build_index method, which can be used to
build a catalog of released Rust versions. In addition, for all solution except RustDistWithCLI, it is possible to let this crate
fetch the required input documents.
Implemented options
1: Currently most of the rust-releases public API supports only stable. Support for the beta and nightly channel is work-in-progress, and the table currently lists whether there is theoretical support for these channels.
2: Speed for the Source trait primarily consist of parsing speed
3: Speed for the FetchResources trait is primarily limited by your own download speed, and the rate limiting of the server from which the resources are fetched
4: Approximate as of 2021-03-03
Which data source should I use?
Since support for the beta and nightly channels is work-in-progress, I would advise to use the RustChangelog data source as it's
a small download, immediately up-to-date on release and fast to parse. It only supports stable channel releases.
Alternatively, the RustDist or RustDistWithCLI data sources can be useful, especially when support for the beta and nightly channel are added.
They both get their input data from the Rust AWS S3 distribution bucket. When using RustDist, the input data can be obtained
with the FetchResources trait implementation. For RustDistWithCLI, you have to obtain the input data yourself (by running the
aws cli with the following options aws --no-sign-request s3 ls static-rust-lang-org/dist/ > dist.txt(source)).
You should not use the ChannelManifests source, unless you have a good reason to do so. This source had a lot of potential, as the input data is the most complete (although with a bit of extra work we can get the same data with RustDist).
With the published channel manifests, we could easily extend information about releases beyond the release version. The separate manifest files could be parsed rather fast, and
new manifests can be downloaded iteratively.
There were however also major downsides. The initial download is quite large, and slow (because of rate limiting), in the order of hours, and,
the resource is approximately one-week out of date since the root manifest is only updated one week after a release (source).
Most importantly however, the input data has not been updated since 2020-02-23(#9). As a result, this source has been deprecated, and will not be further extended.
Applications
cargo-msrv is a tool which can be used to determine the minimal supported Rust version (MSRV).
It builds your Rust crate and checks whether the build succeeds or fails, as this gives the most complete idea whether a version will work
with your (external) dependencies. cargo-msrv uses bisection, or a reverse-linear search, to find the lowest appropriate Rust version.
For this, it needs to have an idea about the toolchains which have been released, and can be installed.
Originally we simply parsed the latest channel manifest, and then decreased the minor semver version, but this was obviously not great for many reasons, including:
- Except for the latest released version, we are left guessing the decreased version numbers actually exist
- Only stable versions were supported, not nightly, beta, or other channels
- Only 1.x.0 versions were supported
This was not ideal, thus rust-releases was born. Now cargo-msrv can iterate over Rust releases of which we know they exist and are available.